Node / ReticulumProjects / LXMF.git / files / README.md

Displaying Raw • View rendered • Download

Tc9d1d9# Lightweight Extensible Message Format

LXMF is a simple and flexible messaging format and delivery protocol that allows a wide variety of implementations, while using as little bandwidth as possible. It is built on top of [Tff7b72Reticulum](Te6edf3a8d24177d946de4f1f0a0fe1af9a1338:/page/repo.mu`g=reticulum|r=reticulum) and offers zero-conf message routing, end-to-end encryption and Forward Secrecy, and can be transported over any kind of medium that Reticulum supports.

LXMF is efficient enough that it can deliver messages over extremely low-bandwidth systems such as packet radio or LoRa. Encrypted LXMF messages can also be encoded as QR-codes or text-based URIs, allowing completely analog *paper message* transport.

User-facing clients built on LXMF include:

Tff7b72- [Tff7b72Sideband](Te6edf3https://unsigned.io/sideband)

Tff7b72- [Tff7b72MeshChat](Te6edf3https://github.com/liamcottle/reticulum-meshchat)

Tff7b72- [Tff7b72Nomad Network](Te6edf3https://unsigned.io/nomadnet)

Community-provided tools and utilities for LXMF include:

Tff7b72- [Tff7b72LXMFy](Te6edf3https://lxmfy.quad4.io/)

Tff7b72- [Tff7b72LXMF-Bot](Te6edf3https://github.com/randogoth/lxmf-bot)

Tff7b72- [Tff7b72LXMF Messageboard](Te6edf3https://github.com/chengtripp/lxmf_messageboard)

Tff7b72- [Tff7b72LXMEvent](Te6edf3https://github.com/faragher/LXMEvent)

Tff7b72- [Tff7b72RangeMap](Te6edf3https://github.com/faragher/RangeMap)

Tff7b72- [Tff7b72LXMF Tools](Te6edf3https://github.com/SebastianObi/LXMF-Tools)

Tc9d1d9## Structure

LXMF messages are stored in a simple and efficient format, that's easy to parse and write.

Tc9d1d9### The format follows this general structure:

Tff7b72- Destination

Tff7b72- Source

Tff7b72- Ed25519 Signature

Tff7b72- Payload

Tff7b72- Timestamp

Tff7b72- Content

Tff7b72- Title

Tff7b72- Fields

Tc9d1d9### And these rules:

Tff7b721. A LXMF message is identified by its __message-id__, which is a SHA-256 hash of the __Destination__, __Source__ and __Payload__. The message-id is never included directly in the message, since it can always be inferred from the message itself.

In some cases the actual message-id cannot be inferred, for example when a Propagation Node is storing an encrypted message for an offline user. In these cases a _transient-id_ is used to identify the message while in storage or transit.

Tff7b722. __Destination__, __Source__, __Signature__ and __Payload__ parts are mandatory, as is the __Timestamp__ part of the payload.

Tff7b72- The __Destination__ and __Source__ fields are 16-byte Reticulum destination hashes

Tff7b72- The __Signature__ field is a 64-byte Ed25519 signature of the __Destination__, __Source__, __Payload__ and __message-id__

Tff7b72- The __Payload__ part is a [Tff7b72msgpacked](Te6edf3https://msgpack.org) list containing four items:

Tff7b721. The __Timestamp__ is a double-precision floating point number representing the number of seconds since the UNIX epoch.

Tff7b722. The __Content__ is the optional content or body of the message

Tff7b723. The __Title__ is an optional title for the message

Tff7b724. The __Fields__ is an optional dictionary

Tff7b723. The __Content__, __Title__ and __Fields__ parts must be included in the message structure, but can be left empty.

Tff7b724. The __Fields__ part can be left empty, or contain a dictionary of any structure or depth.

Tc9d1d9## Usage Examples

LXMF offers flexibility to implement many different messaging schemes, ranging from human communication to machine control and sensor monitoring. Here are a few examples:

Tff7b72- A messaging system for passing short, simple messages between human users, akin to SMS can be implemented using only the __Content__ field, and leaving all other optional fields empty.

Tff7b72- For sending full-size mail, an email-like system can be implemented using the __Title__ and __Content__ fields to store "subject" and "body" parts of the message, and optionally the __Fields__ part can be used to store attachments or other metadata.

Tff7b72- Machine-control messages or sensor readings can be implemented using command structures embedded in the __Fields__ dictionary.

Tff7b72- Distributed discussion or news-groups, akin to USENET or similar systems, can be implemented using the relevant fields and LXMF Propagation Nodes. Broadcast bulletins can be implemented in a similar fashion.

Tc9d1d9## Propagation Nodes

LXM Propagation Nodes offer a way to store and forward messages to users or endpoints that are not directly reachable at the time of message emission. Propagation Nodes can also provide infrastructure for distributed bulletin, news or discussion boards.

When Propagation Nodes exist on a Reticulum network, they will by default peer with each other and synchronise messages, automatically creating an encrypted, distributed message store. Users and other endpoints can retrieve messages destined for them from any available Propagation Nodes on the network.

Tc9d1d9## The LXM Router

The LXM Router handles transporting messages over a Reticulum network, managing delivery receipts, outbound and inbound queues, and is the point of API interaction for client programs. The LXM Router also implements functionality for acting as an LXMF Propagation Node.

Programatically, using the LXM Router to send a message is as simple as:

Ta5d6ff```Ta5d6ffpython

Tff7b72import T7ee787LXMF

Te6edf3lxm_router Tff7b72= Te6edf3LXMFTff7b72.Td2a8ffLXMRouterTb4b4b4(Tb4b4b4)

Te6edf3message Tff7b72= Te6edf3LXMFTff7b72.Td2a8ffLXMessageTb4b4b4(Te6edf3destinationTb4b4b4, Te6edf3sourceTb4b4b4, Ta5d6ff"Ta5d6ffThis is a short, simple message.Ta5d6ff"Tb4b4b4)

Te6edf3lxm_routerTff7b72.Td2a8ffhandle_outboundTb4b4b4(Te6edf3messageTb4b4b4)

Ta5d6ff```

The LXM Router then handles the heavy lifting, such as message packing, encryption, delivery confirmation, path lookup, routing, retries and failure notifications.

Tc9d1d9## Transport Encryption

LXMF uses encryption provided by [Tff7b72Reticulum](Te6edf3https://reticulum.network), and thus uses end-to-end encryption by default. The delivery method of a message will influence which transport encryption scheme is used.

Tff7b72- If a message is delivered over a Reticulum link (which is the default method), the message will be encrypted with ephemeral AES-128 keys derived with ECDH on Curve25519. This mode offers forward secrecy.

Tff7b72- A message can be delivered opportunistically, embedded in a single Reticulum packet. In this cases the message will be opportunistically routed through the network, and will be encrypted with per-packet AES-128 keys derived with ECDH on Curve25519.

Tff7b72- If a message is delivered to the Reticulum GROUP destination type, the message will be encrypted using the symmetric AES-128 key of the GROUP destination.

Tc9d1d9## Wire Format & Overhead

Assuming the default Reticulum configuration, the binary wire-format is as follows:

Tff7b72- 16 bytes destination hash

Tff7b72- 16 bytes source hash

Tff7b72- 64 bytes Ed25519 signature

Tff7b72- Remaining bytes of [Tff7b72msgpack](Te6edf3https://msgpack.org) payload data, in accordance with the structure defined above

The complete message overhead for LXMF is only 111 bytes, which in return gives you timestamped, digitally signed, infinitely extensible, end-to-end encrypted, zero-conf routed, minimal-infrastructure messaging that's easy to use and build applications with.

Tc9d1d9## Code Examples

Before writing your own programs using LXMF, you need to have a basic understanding of how the [Tff7b72Reticulum](Te6edf3https://reticulum.network) protocol and API works. Please see the [Tff7b72Reticulum Manual](Te6edf3https://reticulum.network/manual/). For a few simple examples of how to send and receive messages with LXMF, please see the [Tff7b72receiver example](Te6edf3./docs/example_receiver.py) and the [Tff7b72sender example](Te6edf3./docs/example_sender.py) included in this repository.

Tc9d1d9## Example Paper Message

You can try out the paper messaging functionality by using the following QR code. It is a paper message sent to the LXMF address Ta5d6ff`6b3362bd2c1dbf87b66a85f79a8d8c75`. To be able to decrypt and read the message, you will need to import the following Reticulum Identity to an LXMF messaging app:

Ta5d6ff`3BPTDTQCRZPKJT3TXAJCMQFMOYWIM3OCLKPWMG4HCF2T4CH3YZHVNHNRDU6QAZWV2KBHMWBNT2C62TQEVC5GLFM4MN25VLZFSK3ADRQ=`

The [Tff7b72Sideband](Te6edf3https://unsigned.io/sideband) application allows you to do this easily. After you have imported the identity into an app of your choice, you can scan the following QR code and open it in the app, where it will be decrypted and added as a message.

[Tff7b72Paper message QR code](Te6edf3a8d24177d946de4f1f0a0fe1af9a1338:/page/blob.mu`g=reticulum|r=lxmf|ref=HEAD|path=docs/paper_msg_test.png)

You can also find the entire message in this link:

Ta5d6ff```

lxm://azNivSwdv4e2aoX3mo2MdTAozuI7BlzrLlHULmnVgpz3dNT9CMPVwgywzCJP8FVogj5j_kU7j7ywuvBNcr45kRTrd19c3iHenmnSDe4VEd6FuGsAiT0Khzl7T81YZHPTDhRNp0FdhDE9AJ7uphw7zKMyqhHHxOxqrYeBeKF66gpPxDceqjsOApvsSwggjcuHBx9OxOBy05XmnJxA1unCKgvNfOFYc1T47luxoY3c0dLOJnJPwZuFRytx2TXlQNZzOJ28yTEygIfkDqEO9mZi5lgev7XZJ0DvgioQxMIyoCm7lBUzfq66zW3SQj6vHHph7bhr36dLOCFgk4fZA6yia2MlTT9KV66Tn2l8mPNDlvuSAJhwDA_xx2PN9zKadCjo9sItkAp8r-Ss1CzoUWZUAyT1oDw7ly6RrzGBG-e3eM3CL6u1juIeFiHby7_3cON-6VTUuk4xR5nwKlFTu5vsYMVXe5H3VahiDSS4Q1aqX7I

```

On operating systems that allow for registering custom URI-handlers, you can click the link, and it will be decoded directly in your LXMF client. This works with Sideband on Android.

Tc9d1d9## Installation

If you want to try out LXMF, you can install it with pip:

Ta5d6ff```Ta5d6ffbash

pip install lxmf

Ta5d6ff```

If you are using an operating system that blocks normal user package installation via Ta5d6ff`pip`,

you can return Ta5d6ff`pip` to normal behaviour by editing the Ta5d6ff`~/.config/pip/pip.conf` file,

and adding the following directive in the Ta5d6ff`[global]` section:

Ta5d6ff```Ta5d6fftext

[global]

break-system-packages = true

Ta5d6ff```

Alternatively, you can use the Ta5d6ff`pipx` tool to install Reticulum in an isolated environment:

Ta5d6ff```Ta5d6ffbash

pipx install lxmf

Ta5d6ff```

Tc9d1d9## Daemon Included

The Ta5d6ff`lxmf` package comes with the Ta5d6ff`lxmd` program, a fully functional (but lightweight) LXMF message router and propagation node daemon. After installing the Ta5d6ff`lxmf` package, you can run Ta5d6ff`lxmd --help` to learn more about the command-line options:

Ta5d6ff```Ta5d6fftext

$ lxmd --help

usage: lxmd [-h] [--config CONFIG] [--rnsconfig RNSCONFIG] [-p] [-i PATH] [-v] [-q] [-s] [--exampleconfig] [--version]

Lightweight Extensible Messaging Daemon

options:

-h, --help show this help message and exit

--config CONFIG path to alternative lxmd config directory

--rnsconfig RNSCONFIG

path to alternative Reticulum config directory

-p, --propagation-node

run an LXMF Propagation Node

-i PATH, --on-inbound PATH

executable to run when a message is received

-v, --verbose

-q, --quiet

-s, --service lxmd is running as a service and should log to file

--exampleconfig print verbose configuration example to stdout and exit

--version show program's version number and exit

Ta5d6ff```

Or run Ta5d6ff`lxmd --exampleconfig` to generate a commented example configuration documenting all the available configuration directives.

Tc9d1d9## Support LXMF Development

You can help support the continued development of open, free and private communications systems by donating via one of the following channels:

Tff7b72- Monero:

Ta5d6ff ```

84FpY1QbxHcgdseePYNmhTHcrgMX4nFfBYtz2GKYToqHVVhJp8Eaw1Z1EedRnKD19b3B8NiLCGVxzKV17UMmmeEsCrPyA5w

```

Tff7b72- Bitcoin

Ta5d6ff ```

bc1pgqgu8h8xvj4jtafslq396v7ju7hkgymyrzyqft4llfslz5vp99psqfk3a6

```

Tff7b72- Ethereum

Ta5d6ff ```

0x91C421DdfB8a30a49A71d63447ddb54cEBe3465E

```

Tff7b72- Liberapay: https://liberapay.com/Reticulum/

Tff7b72- Ko-Fi: https://ko-fi.com/markqvist

Tc9d1d9## Caveat Emptor

LXMF is beta software, and should be considered experimental. While it has been built with cryptography best practices very foremost in mind, it _has not_ been externally security audited, and there could very well be privacy-breaking bugs. If you want to help out, or help sponsor an audit, please do get in touch.

Tc9d1d9## Development Roadmap

LXMF is actively being developed, and the following improvements and features are currently planned for implementation:

Tff7b72- Sneakernet and physical transport functionality

Tff7b72- Content Destinations, and easy to use API for group messaging and discussion threads

Tff7b72- Write and release full API and protocol documentation

Tff7b72- Documenting and possibly expanding LXMF limits and priorities